/**
 * @addtogroup printf.h
 * printf.h
 * @{
 */
/**
 * @file ofc_printf.h
 * @brief 格式化字符串的功能库
 * @note 
 * @author Leo

 * @par          修改日志
 * <table>
 * <tr><th>Date     <th>Version <th>Author  <th>Description
 * <tr><td>2020-6-11<td>1.0 <td>Leo <td>创建初始版本
 * <tr><td>2021-07-17<td>1.1 <td>Leo <td>1. 修正"%s"参数输出异常的bug; 2. 新增OfVSPrintfMeasureSize函数
 * @copyright 杭州鸿泉物联网技术股份有限公司
 */

#ifndef _OFC_PRINTF_H_
#define _OFC_PRINTF_H_

#include "ofc_types.h"
#include <stdarg.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * 格式化字符串到str
 * - 格式化模板:"%" [flags] [width] ["." precision] specifier
 * - flags: \n
 *   "-": 左对齐; 默认右对齐 \n
 *   "+": 如果输出值不为负数,则在数值前面加上"+" \n
 *   " ": 如果输出不带符号,则用空格代替符号位
 * - width: 输出宽度,可以为"*",表示输出宽度由参数指定
 * - precision: 输出精度; 如果有效位数不足,则前面用"0"填充
 * - specifier: \n
     "d", "i": 输出有符号的整型 \n
     "u": 输出无符号的整型 \n
     "x": 输出十六进制数 \n
     "c": 输出字符 \n
     "s": 输出字符串 \n
     "p": 输出地址指针 \n
     "%": 输出"%" \n
     "f": 输出浮点数;  注: 浮点数的精度最大支持9
 
 * @param str: 输出字符串缓冲区; 缓冲区必须足够大
 * @param fmt: 格式化字符串
 * @param ...: 数据值列表
 * @return 返回输出长度,不含后面的空0
 */
Int32 OfSPrintf(char *str, const char *fmt, ...);

/**
 * 格式化字符串到str; 参见[OfSPrintf](@ref OfSPrintf)
 * @param str: 输出字符串缓冲区; 缓冲区必须足够大
 * @param fmt: 格式化字符串
 * @param args: 数据值列表
 * @return 返回输出长度,不含后面的空0
 */
Int32 OfVSPrintf(char *str, const char *fmt, va_list args);

/**
 * 测量格式化后的字符串的最大长度(非精确的长度,实际输出的长度可能小于这个返回值);
 * @param fmt: 格式化字符串
 * @param args: 数据值列表
 * @return 返回最大长度,不含后面的空0
 */
Int32 OfVSPrintfMeasureSize(const char *fmt, va_list args);

#ifdef __cplusplus
}  // extern "C"
#endif

#endif // _OFC_PRINTF_H_

/**
 * @}
 */
